NetNews Offline 2/NetNews Offline Volume 2.iso/news/comp/sys/amiga/programmer/4479

Internet Message Format | 1996-08-05 | 14.9 KB

From: [e-mail] (Steffen Haeuser)
Path: eisbaer.bb.bawue.de!birdland.es.bawue.de
Newsgroups: comp.sys.amiga.programmer
Message-ID: <64000305731532830000@BIRDLAND>
X-Mailer: fastnet2rfc V2.0 - (tse) [e-mail] / [e-mail]
Organization: Birdland BBS, Dettingen/Teck, South Germany, [phone]
Content-Type: text/plain; charset=ISO-8859-1
Subject: rtgmaster c2p standard...
Date: 29 Feb 1996 17:14:43


The RtgMaster c2p Standard
==========================

rtgmaster.library is a soon to be released ASM written Library for
Graphicsboard AND ECS/AGA compatibility in games and demos. It is
NOT a WB Emulation, but contrary to some WB Emulations it is done
in a way that make that things, that demo/game coders need, EASY
TO DO.

Among its features, rtgmaster.library (a Beta version is available
from me, [e-mail]), supports a standard for
c2p functions. This will used with the rtgmaster call CallRtgC2P.
CallRtgC2P performs a simple "CopyPixelArray" style function for
Graphics Boards (but does not use the OS, instead it directly
accesses the Video Memory, using longword access where possible),
and performs c2p for ECS/AGA. The c2p is choosable from a file
and the c2p function will be loaded during opening the screen.
This file describes how you can change your c2p algorithm so that
it is usable with rtgmaster.library (you can choose the c2p using
the Screenmode Requester of rtgmaster.library).

I myself will soon convert two 68020 optimized and two 68040 optimized
c2p functions. I would be very interested in other people converting
other c2p code, especially interested i would be in 1x2, 2x1 and 2x2
stuff (i do not have such stuff up to now...)

Now, let's start... i hope this specification satisfies everybody, as
i really tried hard to support EVERYTHING what is usefull for c2p.

Primarily our c2p code is ASM code. You code it, assemble it, and put
it to the directory libs:rtgc2p, with the extension .c2p (a
filename could be libs:rtgc2p/040_1.c2p for example).

The c2p file has to have the following structure :

Byte 1 :

  Bit 0 : Supports AGA     256 Colors
  Bit 1 : "        ECS EHB  64 Colors
  Bit 2 : "        ECS      32 Colors
  Bit 3 : "        ECS      16 Colors
  Bit 4 : Supports 68020
  Bit 5 : Supports 68040
  Bit 6 : Supports 68030
  Bit 7 : Supports 68060

  Note : Bit 6 is 0 for 68040
  ONLY c2p. Bit 7 is 0 for stuff that does not run on 060 (as 060 is a bit
  incompatible to the usual stuff...). This is ONLY information given to the
  user in the Screenmode-Requester of rtgmaster.library, it won't be checked.
  You specify 1 if something is supported (or if you do not know), 0 if not.
Byte 2 :

  Bit 0 : Supports 1x1
  Bit 1 : "        1x2
  Bit 2 : "        2x1
  Bit 3 : "        2x2
  Bit 4 : "        2x4
  Bit 5 : "        4x2
  Bit 6 : "        4x4

  If your c2p code is called with a mode it does not support, it should
  simply choose another one that it supports. It should not fail.

Byte 3 :

  Bit 0 : Supports Interleaved Bitmaps
  Bit 1 : Supports Non-Interleaved Bitmaps
  Bit 2 : Needs Initialization
  Bit 3 : Width has to be divisibly by 32
  Bit 4 : Height has to be divisible by 32
  Bit 5 : Supports "Dirty" flag
  Bit 6 : Needs additional buffer of width * height Bytes
  Bit 7 : Supports c2p'ing rectangles smaller than Fullscreen

Byte 4 :

  Bit 0 : Supports Scrambled Chunky
  Bit 1 : Suppors hardware-hacks (won't be called on NOT ECS/AGA Planar hardware)
  Bit 2 : Runs asynchrone (returns BEFORE c2p is finished)
  Bit 3 : Runs on PowerPC 680x0 emulation (well, future compatibility :) )
  Bit 4 : Supports Power Amiga Planar Hardware
  Bit 5 : Supports CyberGraphX 3 Planar Modes

  Bit 3 currently should be 1, as we do not know this ... grin...
  I added Bit 4 to get sure (if Power Amiga will have Planar Modes left).
  Bit 5 is intended for the case that CyberGraphX 3 AGA uses Planar modes.

Byte 5-7 : Nothing
Byte 8-11  : Pointer to a string that describes your code
            (for example "Fast 040 optimized c2p that remembers
            last frame in additional buffer"). Maximum is 255 characters.
Byte 12-15 : Pointer to code for Non-Interleaved Bitmap or 0.
Byte 16-19 : Pointer to code for Interleaved Bitmap or 0.
Byte 20-23 : Pointer to Initialization code or 0.
Byte 24-27 : Pointer to Expunge code or 0.
Byte 28-31 : Length of the .c2p file in Bytes.

The initialization code
=======================

RtgScreen     in a0.
mode          in d0.

RtgScreen is :

STRUCTURE RtgScreen,0
  ULONG rs_LibBase        ; Sub-library base for this ID
  UWORD rs_LibVersion     ; Sub-library version for this ID
  UWORD rs_Pad1
  ULONG rs_GraphicsBoard  ; ID
  STRUCT rs_Reserved,20
  ULONG rs_MouseX
  ULONG rs_MouseY
  APTR  rs_c2pcode
  APTR rs_c2pdata

  ; and here the information for the specific sublibrary
  ; will be. Look at your includes of rtgmaster.library for
  ; more information. Currently ECS/AGA is the only supported
  ; hardware that provides Planar modes.

  LABEL rs_SIZEOF

Example for RtgScreenAMI (rtgAMI.library for ECS/AGA) :

STRUCTURE RtgScreenAMI,0
  STRUCT rsAMI_Header,rs_SIZEOF
  UWORD rsAMI_Locks
  ALIGNLONG
  ULONG rsAMI_ScreenHandle
  ULONG rsAMI_PlaneSize
  ULONG rsAMI_DispBuf      ;Buffer currently displayed
  ULONG rsAMI_ChipMem1
  ULONG rsAMI_ChipMem2
  ULONG rsAMI_ChipMem3
  STRUCT rsAMI_Bitmap1,40
  STRUCT rsAMI_Bitmap2,40
  STRUCT rsAMI_Bitmap3,40
  LABEL rsAMI_SIZEOF


You will find a lot of stuff here, that could be useful for
your c2p code... an Intuition Screenhandle, the Planesize of the
Bitmap(s), the number of the Buffer currently displayed, the
chipmem addresses of the three buffers and the three Bitmaps
of the screen (remember, rtgmaster.library supports up to
Triple-Buffering). rsAMI_Header is the Above RtgScreen structure.

rb_c2pcode which contains a pointer to the stuff in the choosen
.c2p file in memory. The .c2p file will be loaded to memory during
the OpenRtgScreen call. This indicates, that loading the c2p code
has to be done by EVERY rtg sublibrary that supports planar modes.

rb_c2pdata which should contain a pointer to anything you allocated
in the initialization code of your c2p. You are in NOW WAY limited
in what you do in the initialization function (but you should return
the memory to the system during expunge. Expunge will be called as
soon as you do a c2p with mode c2p_Expunge. There won't be a c2p called
then, instead only an expunge will be done and rb_c2pdata will be set
to 0. Initialization will be called if a c2p is called and rb_c2pdata
is 0). On any way Expunge should free the memory of your c2p code
(rb_c2pcode), so a c2p with mode c2p_Expunge should be called for ANY
application before quit. (so EVERY rtgmaster c2p has an expunge, but
NOT every one has an initialization, as loading the function is done
by rtgmaster itself...)

Remember : Normally RtgScreenAMI is a private structure to rtgmaster.library,
but you are allowed to use it in c2p functions...

The modes : (as defined in include:rtgmaster/rtgmaster.i)

c2p_1x1 EQU 1
c2p_1x2 EQU 2
c2p_2x1 EQU 3
c2p_2x2 EQU 4
c2p_2x4 EQU 5
c2p_4x2 EQU 6
c2p_4x4 EQU 7
c2p_Best EQU 8
c2p_Fastest EQU 9
c2p_Selected EQU 10

These are the modes that have the "dirty" flag set to 0. For certain
c2p algorithms a dirty flag of 1 indicates that not all 32 pixel units
of the screen need to be redrawn. Best chooses the mode with the
highest resolution, Fastest the one which performs the fastest c2p,
Selected the one that is selected for this system (this stuff is saved in
envarc:rtgmaster/c2pmode, if for example c2pmode is the string c2p_1x1,
then 1x1 with "dirty" set to 0, will be used). BTW, the used c2p function
(its path) is saved in envarc:rtgmaster/c2p. This is a GLOBAL configuration
for your system.

c2p_1x1D EQU 11
c2p_1x2D EQU 12
c2p_2x1D EQU 13
c2p_2x2D EQU 14
c2p_2x4D EQU 15
c2p_4x2D EQU 16
c2p_4x4D EQU 17
c2p_BestD EQU 18
c2p_FastestD EQU 19
c2p_SelectedD EQU 20

The same, only with "Dirty" set to 1. If a c2p does not support "dirty" flags,
"dirty" is ignored.

And, last, but not least :

c2p_Expunge EQU 21

If the program wants a mode that is not available, use another similar
mode. Do not fail the program because a mode is not found. But return
a c2p_err_Wrong_Pixelmode anyways.

The Expunge function
====================

RtgScreen in a0.

The c2p function itself
=======================

You will have to code one or two functions (interleaved/non-interleaved).
If CallRtgC2P does not find the needed function, but only 0 (if you only
did it interleaved, and the RtgScreen is non-interleaved, for example)
the CallRtgC2P fails with a c2p_err_Interleavedmode error and does not
perform c2p. This includes specifiying a "dirty" mode, if the c2p does
not support "dirty" modes.

If the user wanted to do a c2p with only part of the display, but your
c2p only supports Fullscreen c2p, CallRtgC2P will return a c2p_err_Windowsize
error (it will check for this at first, for speed issues, so you could try to
do a partially c2p in an application first, and if that fails, recalculate to
do the stuff fullscreen from now on).

If you try to do a c2p with the wrong Colordepth, CallRtgC2P will return
a c2p_err_Wrong_Colordepth error and won't do a c2p.

If you try to do a c2p with a wrong width/height for c2p functions that
are only for "divisible by 32" stuff, a c2p_err_divisible will be given,
but the code will TRY to do the c2p anyways. But normally this should not
happen, if you do not hack around with rtgmaster, as not fitting Screenmodes
are filtered out by the Screenmoderequester.

A c2p_err_hardware will be given if for example you try to do hardware
hacking c2p on other devices than ECS/AGA (but up to now ECS/AGA is
the only supported Planar Hardware on rtgmaster anyways) or other
similar compatibility problems.

For internal errors in your c2p (no memory left...) you might
return c2p_err_internal.

If everything worked fine, CallRtgC2P will return 0.

The errormessages :

c2p_err_Interleavedmode EQU 1
c2p_err_Wrong_Colordepth EQU 2
c2p_err_Wrong_Pixelmode EQU 3
c2p_err_Windowsize EQU 4
c2p_err_divisible EQU 5
c2p_err_hardware EQU 6
c2p_err_internal EQU 7

And now finally, the specification of the c2p function itself :

a0 : Pointer to the chunky data
a1 : Pointer to Bitplane 0
a2 : Pointer to a Byte containing the Dirty Flag
a3 : Pointer to the RtgScreen Structure
d1 : Planesize : (width*height)/8
a5 : Buffer of width*height Bytes, if needed (should be allocated
     in the initialization function, if Byte 3/Bit 6 is 0, you will
     find 0 in a5... you should specify the "Initialization function
     needed" for EVERY c2p that needs this extra buffer, else you will
     get buggy code.
d0 : Modus
a4 : Pointer to a rectangle (like definded in include:graphics/gfx.i)
     indicating which rectangle to handle if you do not want a Fullscreen
     c2p (but remember, not all c2p functions support this feature,
     this could fail...)
d2 : For asynchrone stuff : Exec Signal

Providing the correct Bitmap of the three is already handled by
rtgmaster.library, you won't have to bother about it... you should
restore ALL registers, only d0,d1,a0 and a1 might loose their contents
in your c2p.

d2 contains an Exec Signal (an ULONG containing a signal bit). For
asynchrone code this signal has to be set as soon as the c2p is
finished. Synchrone code should set the signal at the end of the
function. Do not ignore the signal !!! Even if you have a synchronce
function !!!

The function returns 0, if it worked, or an appropriate errorcode, if
not. Sometimes it might even then doing something if there was an
errorcode (look above).

Finally, the specification for CallRtgC2P :

rtgmaster.library/CallRtgC2P                                rtgmaster.library/CallRtgC2P

   NAME
        CallRtgC2P -- Perform c2p for Planar Screens, CopyRtgPixelArray for Chunky Screens

   SYNOPSIS
        int CallRtgC2P(RtgScreen,BufAdr,Array,signal,xpos,ypos,width,height,mode)
         D0              A0        A1     A2    D0     D1   D2   D3    D4     D5

        int CallRtgC2P(struct RtgScreen *,APTR,APTR,ULONG,ULONG,ULONG,ULONG,ULONG,ULONG)

   FUNCTION
        This function will look what the "standard c2p" for the system is up to now
        (the standard c2p can be choose by a future version of the Rtgmaster Screenmode
        requester, the available c2p algorithms are found in libs:rtgc2p, how own c2p
        algorithms can be added to the system will be explained in the documentation
        of the first version of rtgmaster.library that actually supports CallRtgC2P).
        The function will, if the display is a Planar one, convert the Chunky Data in
        Array to Planar using the choosen c2p algorithm, and display it in the choosen
        Buffer. For Chunky Displays it will instead do the same as CopyRtgChunkyPixel.
        This way a very easy possibility to support both AGA and Graphics Boards without
        having to do "special versions" will be available, if one uses a Fastram Buffer.

        I am still looking for c2p algorithms for this function !!! All used c2p algorithms
        should support AGA and additional, it would be fine, if they supported
        1x1,1x2,2x1 and 2x2. If you have fine c2p algorithms, mail me
        ([e-mail]).

        NOTE : The Array should EXACTLY be as big as specified with Left, Top, Width
        and Height... it should *NOT* be bigger. Up to now the c2p i have do not
        support the feature to do less then fullscreen...

        NOTE: Currently you *HAVE TO* use xpos=0 ypos=0 width=<max x> height=<max y>
        Maybe this will change in the future !!!!!!!!!!!!!!

        NOTE: Some c2p algorithms might do NOTHING in certain colour depths, chunky modes
        or for interleaved bitmaps. Be careful about this. If the c2p works,
        this function returns 0, otherwise an errorcode.

        Principially it COULD support 256, 64 (EHB), 32 or 16 colors and 1x1, 1x2, 2x1,
        2x2,4x2,2x4 and 4x4 (look at the includes). It is also possible to choose the
        FASTEST AVAILABLE, the BEST AVAILABLE mode or the mode that was selected from
        the user as standard mode for his system, using the Screenmode Requester.

        Before quitting the program you should call this function with a mode
        of c2p_Expunge to free used memory in initializations.

        If the user did not specify a standard c2p, this function will use the fastest
        available mode.

        The signal indicates (for asynchrone c2p) that the c2p has done. For synchrone
        ones it is set after quitting the function.

        In mode you specify which c2p mode to use.

        For Graphics Boards, ALWAYS 1x1 is used.

        IMPLEMENTED WITH SUBLIBRARIES WITH AT LEAST VERSION 2.0 (none up to now...)

   INPUTS
        RtgScreen - The RtgScreen to use.
        BufAdr - The address of the buffer to use
        Array - The fastram buffer
        Left - The x position on the Bitmap of RtgScreen where to put the stuff
        Top - The y position
        Width - The Width of the stuff
        Height - The Height of the stuff

   SEE ALSO